package com.github.xtranslation.core.repository;

import java.lang.annotation.Annotation;
import java.util.Collections;
import java.util.List;
import java.util.Map;


/**
 * TransRepository: 翻译数据仓库接口
 * <p>
 * 翻译框架的核心数据访问接口，定义了获取翻译数据的标准方法。
 * 所有具体的翻译仓库实现类都必须实现此接口，以提供统一的翻译数据访问能力。
 * </p>
 * <p>
 * 核心职责：
 * 1. 数据访问标准：定义获取翻译数据的统一接口
 * 2. 扩展支持：支持用户自定义数据源实现
 * 3. 注解处理：处理翻译注解中的元数据信息
 *
 * @author zhangxiaoxiang
 * @see com.github.xtranslation.core.repository.dict.DictTransRepository
 * @see com.github.xtranslation.core.repository.TransRepositoryFactory
 * @since 2025/7/27
 */
public interface TransRepository {

    /**
     * 获取翻译值映射
     * <p>
     * 根据需要翻译的ID列表和翻译注解信息，获取对应的翻译数据映射。
     * 返回的映射中，键为原始值（通常是ID），值为翻译后的对象。
     * </p>
     * <p>
     * 参数说明：
     * 1. transIdList：需要翻译的ID列表，通常是源字段的值集合
     * 2. transAnno：翻译注解，包含翻译配置信息
     * </p>
     * <p>
     * 返回值说明：
     * Map的键为原始值（如用户ID），值为翻译后的完整对象（如User对象）
     * 例如：{ 1 - User{id=1, name="张三"}, 2 - User{id=2, name="李四"} }
     * </p>
     * <p>
     * 实现建议：
     * 1. 线程安全：实现类应保证在多线程环境下的安全性
     * 2. 性能优化：考虑缓存机制避免重复查询
     * 3. 异常处理：合理处理数据访问过程中的异常情况
     * 4. 空值处理：当无数据时应返回空Map而非null
     * </p>
     *
     * @param transIdList 需要翻译的ID列表，通常是源字段的值集合
     * @param transAnno   翻译对象上的注解，包含翻译配置信息
     * @return 翻译值映射，键为原始值，值为翻译后的对象
     * 当无数据或发生错误时应返回空Map而非null
     */
    default Map<Object, Object> getTransValueMap(List<Object> transIdList, Annotation transAnno) {
        return Collections.emptyMap();
    }

}
